Pepvoid Builder Technical Manual

Welcome to the technical documentation for Pepvoid Builder, a multi-architecture toolkit for building customized Void Linux images.

                  _     _                      _  _     _                 
  _   ___ (_) __| |   |__  _  _  _ | |__| |___  _ __ 
 | |/ / _ \| |/ _` |  | '_ \| | | | | | / _` / _ \| '__|
 | < (_) | | (_| |  | |_) | |_| | |_| | (_| | __/ |   
 |_|\_\___/|_|\__,_|  |_.__/ \__,_|\__,_|\__,_|\___|_|

Technical Documentation Index

User Guide

Architecture & Bootloaders

Additional Guides and Design Notes

Overview & Architecture Highlights

Pepvoid Builder is a Python toolkit for assembling bootable live ISO images, raw Single-Board Computer (SBC) disk images, and container rootfs archives for Void Linux. Its architecture separates configuration resolution, host toolchain management, chroot management, system customization, and output finalization.

Key Capabilities

  • 🌐 22 Supported Build Targets: the 17 architecture profiles plus the board targets rockpro64, pine64, odroid-c4, odroid-n2, and visionfive2. A configured target does not certify a successful build or physical-device boot; see the hardware validation notes.

  • 🎯 Unified Presets & Flavours (-P / --preset): Ready-to-build editions (minimal, desktop-xfce, desktop-kde, desktop-gnome, workplace, rescue-sysadmin, education, developer, gaming).

  • ⚡ Build Performance Options (--fast, --tmpfs, --benchmark): Fast-mode compression and staging options, optional RAM-backed work storage, and per-stage timing reports. Actual speed depends on the host and selected build.

  • 📦 Stage Seed Tarballs (--use-tarball, --create-tarball): Reuses a base root filesystem to avoid repeating some bootstrap work; build time depends on package changes, network, and host performance.

  • 🔑 Security & SSH Public Key Ingestion: Inject root passwords, lock accounts, and provision SSH keys directly into authorized_keys.

  • 🪝 Lifecycle Hooks Engine: Execute custom scripts at pre-install, post-install, pre-iso, and post-iso stages.

  • 🤖 Interactive Wizard Mode (-i / --interactive): Intuitive terminal menu for step-by-step image creation.

  • 🛡️ Isolated Build Toolchain: Uses verified static XBPS tools and per-build toolchain directories; host utilities, network access, and sufficient permissions are still required for real builds.

  • 🧾 Artifact Integrity Metadata: Generates checksum and manifest sidecars. Optional per-build GPG signatures use ephemeral keys and do not authenticate the publisher unless the key fingerprint is independently trusted.

Supported Target Architectures

  1. x86_64: 64-bit x86 with glibc

  2. x86_64-musl: 64-bit x86 with musl

  3. i686: 32-bit x86 with glibc

  4. aarch64: Generic 64-bit ARM with glibc

  5. aarch64-musl: Generic 64-bit ARM with musl

  6. armv7l: 32-bit ARMv7 with glibc

  7. armv7l-musl: 32-bit ARMv7 with musl

  8. armv6l: 32-bit ARMv6 with glibc

  9. armv6l-musl: 32-bit ARMv6 with musl

  10. riscv64: 64-bit RISC-V with glibc

  11. riscv64-musl: 64-bit RISC-V with musl

  12. rpi-aarch64: Raspberry Pi 64-bit profile

  13. rpi-armv7l: Raspberry Pi 32-bit ARMv7 profile

  14. rpi-armv6l: Raspberry Pi 32-bit ARMv6 profile

  15. pinebookpro: Pine64 Pinebook Pro profile

  16. asahi: Apple Silicon Asahi profile

  17. x13s: Lenovo ThinkPad X13s profile

  18. rockpro64: Pine64 RockPro64 profile

  19. pine64: Pine A64 profile

  20. odroid-c4: Hardkernel ODROID-C4 profile

  21. odroid-n2: Hardkernel ODROID-N2/N2+ profile

  22. visionfive2: StarFive VisionFive 2 RISC-V profile

These profiles describe builder configuration support. They are not a claim that all listed devices, boot paths, or desktop environments have passed physical-hardware testing. See the hardware compatibility notes.

Author & Maintainer